// EntityResolver2.java - Extended SAX entity resolver.
// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
// $Id: EntityResolver2.java,v 1.2 2002/01/12 19:20:08 dbrownell Exp $

package org.xml.sax.ext;

import java.io.IOException;
import org.xml.sax.EntityResolver;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.XMLReader;


/**
 * Extended interface for mapping external entity references to input
 * sources, or providing a missing external subset.  The
 * {@link XMLReader#setEntityResolver XMLReader.setEntityResolver()} method
 * is used to provide implementations of this interface to parsers.
 * When a parser uses the methods in this interface, the
 * {@link EntityResolver2#resolveEntity EntityResolver2.resolveEntity()}
 * method (in this interface) is used <em>instead of</em> the older (SAX 1.0)
 * {@link EntityResolver#resolveEntity EntityResolver.resolveEntity()} method.
 *
 * <blockquote>
 * <em>This module, both source code and documentation, is in the
 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
 * </blockquote>
 *
 * <p>If a SAX application requires the customized handling which this
 * interface defines for external entities, it must ensure that it uses
 * an XMLReader with the
 * <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag
 * set to <em>true</em> (which is its default value when the feature is
 * recognized).  If that flag is unrecognized, or its value is false,
 * or the resolver does not implement this interface, then only the
 * {@link EntityResolver} method will be used.
 * </p>
 *
 * <p>That supports three categories of application that modify entity
 * resolution.
 * categories:类别
 * <em>Old Style</em> applications won't know about this interface;
 * they will provide an EntityResolver.
 * <em>Transitional Mode</em> provide an EntityResolver2 and automatically
 * get the benefit of its methods in any systems (parsers or other tools)
 * supporting it, due to polymorphism.
 *transitional：过渡
 * benifit：好处
 * polymorphism:多态性
 *
 * Both <em>Old Style</em> and <em>Transitional Mode</em> applications will
 * work with any SAX2 parser.
 * <em>New style</em> applications will fail to run except on SAX2 parsers
 * that support this particular feature.
 * They will insist that feature flag have a value of "true", and the
 * EntityResolver2 implementation they provide  might throw an exception
 * if the original SAX 1.0 style entity resolution method is invoked.
 * </p>
 *
 * @see org.xml.sax.XMLReader#setEntityResolver
 *
 * @since SAX 2.0 (extensions 1.1 alpha)
 * @author David Brownell
 * @version TBD
 */
public interface EntityResolver2 extends EntityResolver
{
    /**
     * Allows applications to provide an external subset for documents that don't explicitly define one.
     * subsset:子集
     * explicitly:明确的，显示的
     * define:定义
     * 允许应用程序为没有明确定义的文档提供外部子集
     * Documents with DOCTYPE declarations that omit an external subset can thus augment the declarations  available for validation,
     *omit：忽略
     * thus：因此，从而
     * augment:增加
     * available:可用于
     * validation:验证
     * 具有DOCTYPE声明的文档省略了外部子集，因此可以增加可用于验证的声明，
     * entity processing, and attribute processing (normalization, defaulting, and reporting types including ID).
     * 实体处理和属性处理（标准化，默认和包括ID的报告类型）。
     * This augmentation is reported through the {@link LexicalHandler#startDTD startDTD()} method as if the document text had originally included the external subset;
     * ：这个扩充是通过{@link LexicalHandler＃start DTD start DTD（）}方法来报告的，就好像文档文本最初包含外部子集一样;
     * this callback is made before any internal subset data or errors are reported.
     * 此回调在任何内部子集数据或错误报告之前进行
     * </p>
     *
     * <p>This method can also be used with documents that have no DOCTYPE declaration.
     * 此方法也可以用于没有DOCTYPE声明的文档
     * When the root element is encountered, but no DOCTYPE declaration has been seen, this method is invoked.
     * encountered:遇到
     * 遇到根元素，但没有看到DOCTYPE声明时，调用此方法。
     * If it returns a value for the external subset, that root element is declared to be the root element,
     * 如果它为外部子集返回一个值，则该根元素被声明为根元素，
     * giving the effect of splicing a DOCTYPE declaration at the end the prolog of a document that could not otherwise be valid.
     * splicing：拼接
     *prolog：开端
     *valid：有效的
     * 在文档的序言、结尾处给出了拼接DOCTYPE声明的效果，否则该文档是无效的
     * The sequence of parser callbacks in that case logically resembles this:</p>
     *sequence：序列，顺序
     * logically：逻辑
     * resembles：相似的
     * 在这种情况下，解析器回调的顺序在逻辑上与此类似
     * <pre>
     * ... comments and PIs from the prolog (as usual)
     * comments:评论，注释
     * startDTD ("rootName", source.getPublicId (), source.getSystemId ());
     * startEntity ("[dtd]");
     * ... declarations, comments, and PIs from the external subset endEntity ("[dtd]");
     * endDTD ();
     * ... then the rest of the document (as usual)
     * startElement (..., "rootName", ...);
     * </pre>
     *
     * <p>Note that the InputSource gets no further resolution.
     * further:进一步
     * resolution:分辨率，决心，解决，解析
     *请注意，输入源无法进一步解析。
     * Implementations of this method may wish to invoke {@link #resolveEntity resolveEntity()} to gain benefits such as use of local caches of DTD entities.
     * benefits:好处
     * 这个方法的实现可能希望调用{@link #resolveEntity resolveEntity()} 来获得好处，例如使用DTD实体的本地缓存。
     * Also, this method will never be used by a (non-validating) processor that is not including external parameter entities.
     * 而且，这个方法不会被不包含外部参数实体的（非验证）处理器使用
     * </p>
     *
     * <p>Uses for this method include facilitating data validation when interoperating with XML processors that would always require undesirable network accesses for external entities,
     * facilitating：促进
     * validation:验证
     * interoperating;互相操作
     * undesirable:不合理的。不良的
     * 这种方法的使用包括促进与XML处理器互操作时的数据验证，这些处理器总是要求外部实体的不良网络访问
     * or which for other reasons adopt a "no DTDs" policy.
     * adopt：采取
     * 或者出于其他原因采取了"no DTDs" 的政策
     * Non-validation motives include forcing documents to include DTDs so that attributes are handled consistently.
     *motives:动机、目的
     * consistently:一致
     * 非验证动机包括强制文档包含DTD，以便一致地处理属性。
     * For example, an XPath processor needs to know which attibutes have type "ID" before it can process a widely used type of reference.
     * widely：广泛的
     * reference：引用
     * 例如，XPath处理器需要知道哪些属性具有类型“ID”，才能处理广泛使用的引用类型
     * </p>
     *
     * <p><strong>Warning:</strong> Returning an external subset modifies the input document.
     * 返回外部子集修改输入文档
     * By providing definitions for general entities, it can make a malformed document appear to be well formed.
     * definitions：定义
     * malformed：有缺陷的，错误的
     * 通过提供一般实体的定义，它可以使格式错误的文件看起来是正确的
     * </p>
     *
     * @param name Identifies the document root element.
     *             标识文档根元素
     *             This name comes from a DOCTYPE declaration (where available) or from the actual root element.
     *             此名称来自DOCTYPE声明（如果可用）或来自实际的根元素
     * @param baseURI The document's base URI, serving as an additional hint for selecting the external subset.
     *               文档的基本URI，作为选择外部子集的附加提示
     *                This is always an absolute URI, unless it is null because the XMLReader was given an InputSource without one.
     *这总是一个绝对的URI，除非它是空的，因为XMLReader没有一个输入源
     * @return An InputSource object describing the new external subset to be used by the parser, or null to indicate that no external subset is provided.
     *描述解析器使用的新外部子集的Input Source对象，或者指示没有提供外部子集的null。
     * @exception SAXException Any SAX exception, possibly wrapping
     *    another exception.
     * @exception IOException Probably indicating a failure to create
     *    a new InputStream or Reader, or an illegal URL.
     *    illegal:非法的
     */
    public InputSource getExternalSubset (String name, String baseURI)
    throws SAXException, IOException;

    /**
     * Allows applications to map references to external entities into input sources, or tell the parser it should use conventional URI resolution.
     * 允许应用程序将对外部实体的引用映射到输入源，或者告诉解析器应该使用传统的URI解析。
     * This method is only called for external entities which have been properly declared.
     * 这种方法只适用于已经正确声明的外部实体
     * This method provides more flexibility than the {@link EntityResolver} interface,
     * 这种方法比{@link EntityResolver}接口提供了更多的灵活性
     * supporting implementations of more complex catalogue schemes such as the one defined by the
     * 支持更复杂的目录方案的实现，比如由
     * <a href=
    "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
    >OASIS XML Catalogs</a> specification.</p>
     *
     * <p>Parsers configured to use this resolver method will call it to determine the input source to use for any external entity being included because of a reference in the XML text.
     * 配置为使用此解析器方法的解析器将调用它来确定由于XML文本中的引用而被包含的任何外部实体使用的输入源。
     * That excludes the document entity, and any external entity returned by {@link #getExternalSubset getExternalSubset()}.
     * 排除了文档实体和由{@link #getExternalSubset getExternalSubset()}返回的任何外部实体。
     * When a (non-validating) processor is configured not to include
     * a class of entities (parameter or general) through use of feature
     * flags, this method is not invoked for such entities.  </p>
     *
     * <p>Note that the entity naming scheme used here is the same one
     * used in the {@link LexicalHandler}, or in the {@link
    org.xml.sax.ContentHandler#skippedEntity
    ContentHandler.skippedEntity()}
     * method. </p>
     *
     * @param name Identifies the external entity being resolved.
     *    Either "[dtd]" for the external subset, or a name starting
     *    with "%" to indicate a parameter entity, or else the name of
     *    a general entity.  This is never null when invoked by a SAX2
     *    parser.
     * @param publicId The public identifier of the external entity being
     *    referenced (normalized as required by the XML specification), or
     *    null if none was supplied.
     * @param baseURI The URI with respect to which relative systemIDs
     *    are interpreted.  This is always an absolute URI, unless it is
     *    null (likely because the XMLReader was given an InputSource without
     *  one).  This URI is defined by the XML specification to be the one
     *    associated with the "&lt;" starting the relevant declaration.
     * @param systemId The system identifier of the external entity
     *    being referenced; either a relative or absolute URI.
     *  This is never null when invoked by a SAX2 parser; only declared
     *    entities, and any external subset, are resolved by such parsers.
     *
     * @return An InputSource object describing the new input source to
     *    be used by the parser.  Returning null directs the parser to
     *    resolve the system ID against the base URI and open a connection
     *    to resulting URI.
     *
     * @exception SAXException Any SAX exception, possibly wrapping
     *    another exception.
     * @exception IOException Probably indicating a failure to create
     *    a new InputStream or Reader, or an illegal URL.
     */
    public InputSource resolveEntity (
        String name,
        String publicId,
        String baseURI,
        String systemId
    ) throws SAXException, IOException;
}
